package cn.iocoder.yudao.module.reading.service.banner;

import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.module.reading.controller.admin.banner.vo.BannerPageReqVO;
import cn.iocoder.yudao.module.reading.dal.dataobject.banner.BannerDO;

import jakarta.validation.Valid;
import java.time.LocalDateTime;
import java.util.List;

/**
 * 横幅管理 Service 接口
 *
 * @author 李晨
 */
public interface BannerService {

    /**
     * 获得有效的横幅列表
     * 只返回状态为启用且在有效时间范围内的横幅
     *
     * @return 有效横幅列表
     */
    List<BannerDO> getActiveBanners();

    /**
     * 获得有效的横幅列表，限制数量
     *
     * @param limit 限制数量
     * @return 有效横幅列表
     */
    List<BannerDO> getActiveBanners(Integer limit);

    /**
     * 获得横幅
     *
     * @param id 编号
     * @return 横幅
     */
    BannerDO getBanner(Long id);

    /**
     * 根据标题获得横幅
     *
     * @param title 横幅标题
     * @return 横幅
     */
    BannerDO getBannerByTitle(String title);

    /**
     * 记录横幅点击
     *
     * @param id 横幅ID
     */
    void recordBannerClick(Long id);

    // ==================== Admin 管理相关 ====================

    /**
     * 创建横幅
     *
     * @param title 标题
     * @param description 描述
     * @param imageUrl 图片URL
     * @param linkUrl 跳转链接
     * @param linkType 链接类型
     * @param sortOrder 排序权重
     * @param status 状态
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return 编号
     */
    Long createBanner(String title, String description, String imageUrl, String linkUrl, 
                     String linkType, Integer sortOrder, Boolean status, 
                     LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 更新横幅
     *
     * @param id 编号
     * @param title 标题
     * @param description 描述
     * @param imageUrl 图片URL
     * @param linkUrl 跳转链接
     * @param linkType 链接类型
     * @param sortOrder 排序权重
     * @param status 状态
     * @param startTime 开始时间
     * @param endTime 结束时间
     */
    void updateBanner(Long id, String title, String description, String imageUrl, String linkUrl,
                     String linkType, Integer sortOrder, Boolean status,
                     LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 删除横幅
     *
     * @param id 编号
     */
    void deleteBanner(Long id);

    /**
     * 获得横幅分页
     *
     * @param pageReqVO 分页查询条件
     * @return 横幅分页
     */
    PageResult<BannerDO> getBannerPage(BannerPageReqVO pageReqVO);

    /**
     * 批量更新横幅状态
     *
     * @param ids 横幅ID列表
     * @param status 状态
     */
    void updateBannerStatusBatch(List<Long> ids, Boolean status);

    /**
     * 批量删除横幅
     *
     * @param ids 横幅ID列表
     */
    void deleteBannerBatch(List<Long> ids);

}
